home *** CD-ROM | disk | FTP | other *** search
/ Mac Magazin/MacEasy 12 / Mac Magazin and MacEasy Magazine CD - Issue 12.iso / Sharewarebibliothek / Anwendungen / Wissenschaft & Technik / Yorick / yorick11-ppc folder / startup / graph.i < prev    next >
Text File  |  1995-04-03  |  50KB  |  1,117 lines
  1. /*
  2.     GRAPH.I
  3.     Declarations of Yorick graphics functions.
  4.  
  5.     $Id: graph.i,v 1.1 1993/08/27 18:32:09 munro Exp $
  6.  */
  7. /*    Copyright (c) 1994.  The Regents of the University of California.
  8.                     All rights reserved.  */
  9.  
  10. /*--------------------------------------------------------------------------*/
  11. /* Control functions */
  12.  
  13. extern window;
  14. /* DOCUMENT window, n, display="host:server.screen", dpi=100/75, wait=0/1,
  15.                        private=0/1, hcp="hcp_filename", dump=0/1,
  16.                        legends=1/0, style="style_sheet_filename"
  17.      select window N as the current graphics output window.  N may
  18.      range from 0 to 7, inclusive.  Each graphics window corresponds to
  19.      an X window, and optionally has its own associated hardcopy file.
  20.      If N is omitted, it defaults to the current coordinate system.
  21.  
  22.      The X window will appear on your default display at 75 dpi, unless
  23.      you specify the display and/or dpi keywords.  A dpi=100 X window
  24.      is larger than a dpi=75 X window; both represent the same thing
  25.      on paper.  Use display="" to create a graphics window which has
  26.      no associated X window (you should do this if you want to make
  27.      plots in a non-interactive batch mode).
  28.  
  29.      By default, an X window will attempt to use shared colors, which
  30.      permits several Yorick graphics windows (including windows from
  31.      multiple instances of Yorick) to use a common palette.  You can
  32.      force an X window to post its own colormap (set its colormap
  33.      attribute) with the private=1 keyword.  You will most likely have
  34.      to fiddle with your window manager to understand how it handles
  35.      colormap focus if you do this.  Use private=0 to return to shared
  36.      colors.
  37.  
  38.      By default, Yorick will not wait for the X window to become visible;
  39.      code which creates a new window, then plots a series of frames to
  40.      that window should use wait=1 to assure that all frames are actually
  41.      plotted.
  42.  
  43.      By default, a graphics window does NOT have a hardcopy file
  44.      of its own -- any request for hardcopy are directed to the
  45.      default hardcopy file, so hardcopy output from any window goes
  46.      to a single file.  By specifying the hcp keyword, however, a
  47.      hardcopy file unique to this window will be created.  If the
  48.      "hcp_filename" ends in ".ps", the hardcopy file will be a PostScript
  49.      file; otherwise, hardcopy files are in binary CGM format.  Use
  50.      hcp="" to revert to the default hardcopy file (closing the window
  51.      specific file, if any).  The legends keyword, if present, controls
  52.      whether the curve legends are (legends=1, the default) or are not
  53.      (legends=0) dumped to the hardcopy file.  The dump keyword, if
  54.      present, controls whether all colors are converted to a gray scale
  55.      (dump=0, the default), or the current palette is dumped at the
  56.      beginning of each page of hardcopy output.  (The legends keyword
  57.      applies to all pictures dumped to hardcopy from this graphics
  58.      window.  The dump keyword applies only to the specific hardcopy
  59.      file defined using the hcp keyword -- use the dump keyword in the
  60.      hcp_file command to get the same effect in the default hardcopy
  61.      file.)
  62.  
  63.      If both display="" and hcp="", the graphics window will be
  64.      entirely eliminated.
  65.  
  66.      The style keyword, if present, specifies the name of a Gist style
  67.      sheet file; the default is "work.gs".  The style sheet determines
  68.      the number and location of coordinate systems, tick and label styles,
  69.      and the like.  Other choices include "axes.gs", "boxed.gs",
  70.      "work2.gs", and "boxed2.gs".
  71.  
  72.      If invoked as a function, window(...) returns the current
  73.      window number.
  74.    SEE ALSO: plsys, hcp_file, fma, hcp, redraw, palette, animate, plg,
  75.              winkill, gridxy
  76.  */
  77.  
  78. func winkill(n)
  79. /* DOCUMENT winkill
  80.          or winkill, n
  81.      deletes the current graphics window, or graphics window N (0-7).
  82.    SEE ALSO: window
  83.  */
  84. {
  85.   window, n, display="", hcp="";
  86. }
  87.  
  88. extern current_window;
  89. /* DOCUMENT n= current_window()
  90.      returns the number of the current graphics window, or -1 if none.
  91.  */
  92.  
  93. extern hcp_file;
  94. /* DOCUMENT hcp_file, filename, dump=0/1
  95.      sets the default hardcopy file to FILENAME.  If FILENAME ends with
  96.      ".ps", the file will be a PostScript file, otherwise it will be a
  97.      binary CGM file.  By default, the hardcopy file name will be
  98.      "Aa00.cgm", or "Ab00.cgm" if that exists, or "Ac00.cgm" if both
  99.      exist, and so on.  The default hardcopy file gets hardcopy from all
  100.      graphics windows which do not have their own specific hardcopy file
  101.      (see the window command).  If the dump keyword is present and non-zero,
  102.      the current palette will be dumped at the beginning of each frame
  103.      of the default hardcopy file.  With dump=0, the default behavior of
  104.      converting all colors to a gray scale is restored.
  105.    SEE ALSO: window, fma, hcp, plg
  106.  */
  107.  
  108. extern hcp_finish;
  109. /* DOCUMENT filename= hcp_finish()
  110.          or filename= hcp_finish(n)
  111.      closes the current hardcopy file and returns the filename.
  112.      If N is specified, closes the hcp file associated with window N
  113.      and returns its name; use hcp_finish(-1) to close the default
  114.      hardcopy file.
  115.    SEE ALSO: window, fma, hcp, hcp_out, plg
  116.  */
  117.  
  118. func hcp_out(n,keep=)
  119. /* DOCUMENT hcp_out
  120.          or hcp_out, n
  121.      finishes the current hardcopy file and sends it to the printer.
  122.      If N is specified, prints the hcp file associated with window N;
  123.      use hcp_out,-1 to print the default hardcopy file.
  124.      Unless the KEEP keyword is supplied and non-zero, the file will
  125.      be deleted after it is processed by gist and sent to lpr.
  126.    SEE ALSO: window, fma, hcp, hcp_finish, plg
  127.  */
  128. {
  129.   filename= hcp_finish();
  130.   if (filename) {
  131.     if (strpart(filename,-2:0)==".ps")
  132.       system, swrite(format=LPR_FORMAT, filename);
  133.     else
  134.       system, swrite(format=GIST_FORMAT, filename);
  135.     if (!keep) remove, filename;
  136.   }
  137. }
  138.  
  139. func eps(name)
  140. /* DOCUMENT eps, name
  141.      writes the picture in the current graphics window to the Encapsulated
  142.      PostScript file NAME+".epsi" (i.e.- the suffix .epsi is added to NAME).
  143.      The eps function requires the ps2epsi utility which comes with the
  144.      project GNU Ghostscript program.  Any hardcopy file associated with
  145.      the current window is first closed, but the default hardcopy file is
  146.      unaffected.  As a side effect, legends are turned off and color table
  147.      dumping is turned on for the current window.
  148.      The external variable PS2EPSI_FORMAT contains the format for the
  149.      command to start the ps2epsi program.
  150.    SEE ALSO: window, fma, hcp, hcp_finish, plg
  151.  */
  152. {
  153.   name+= ".ps";
  154.   window, hcp=name, dump=1, legends=0;
  155.   hcp;
  156.   window, hcp="";
  157.   system, swrite(format=PS2EPSI_FORMAT, name);
  158.   remove, name;
  159. }
  160. if (is_void(PS2EPSI_FORMAT)) PS2EPSI_FORMAT= "ps2epsi %s";
  161.  
  162. extern fma;
  163. /* DOCUMENT fma
  164.      frame advance the current graphics window.  The current picture
  165.      remains displayed in the associated X window until the next element
  166.      is actually plotted.
  167.    SEE ALSO: window, hcp, animate, plg
  168.  */
  169.  
  170. extern hcp;
  171. extern hcpon;
  172. extern hcpoff;
  173. /* DOCUMENT hcp
  174.             hcpon
  175.         hcpoff
  176.      The hcp command sends the picture displayed in the current graphics
  177.      window to the hardcopy file.  (The name of the default hardcopy file
  178.      can be specified using hcp_file; each individual graphics window may
  179.      have its own hardcopy file as specified by the window command.)
  180.      The hcpon command causes every fma (frame advance) command to do
  181.      and implicit hcp, so that every frame is sent to the hardcopy file.
  182.      The hcpoff command reverts to the default "demand only" mode.
  183.    SEE ALSO: window, fma, plg
  184.  */
  185.  
  186. extern redraw;
  187. /* DOCUMENT redraw
  188.      redraws the X window associated with the current graphics window.
  189.    SEE ALSO: window, fma, hcp, plg
  190.  */
  191.  
  192. extern palette;
  193. /* DOCUMENT palette, filename
  194.          or palette, source_window_number
  195.          or palette, red, green, blue, ntsc=1/0
  196.          or palette, red, green, blue, gray
  197.      or palette, red, green, blue, query=1
  198.      or palette, red, green, blue, gray, query=1
  199.      sets (or retrieves with query=1) the palette for the current
  200.      graphics window.  The FILENAME is the name of a Gist palette file;
  201.      the standard palettes are "earth.gp", "stern.gp", "rainbow.gp",
  202.      "heat.gp", "gray.gp", and "yarg.gp".  Use the maxcolors keyword
  203.      in the pldefault command to put an upper limit on the number of
  204.      colors which will be read from the palette in FILENAME.
  205.  
  206.      In the second form, the palette for the current window is copied
  207.      from the SOURCE_WINDOW_NUMBER.  If the X colormap for the window is
  208.      private, there will still be two separate X colormaps for the two
  209.      windows, but they will have the same color values.
  210.  
  211.      In the third form, RED, GREEN, and BLUE are 1-D arrays of the same
  212.      length specifying the palette you wish to install; the values
  213.      should vary between 0 and 255, and your palette should have no
  214.      more than 240 colors.  If ntsc=0, monochrome devices (such as most
  215.      laser printers) will use the average brightness to translate your
  216.      colors into gray; otherwise, the NTSC (television) averaging will
  217.      be used (.30*RED+.59*GREEN+.11*BLUE).  Alternatively, you can specify
  218.      GRAY explicitly.
  219.  
  220.      Ordinarily, the palette is not dumped to a hardcopy file
  221.      (color hardcopy is still rare and expensive), but you can
  222.      force the palette to dump using the window or hcp_file commands.
  223.    SEE ALSO: window, fma, hcp, pldefault, plg
  224.  */
  225.  
  226. extern animate;
  227. /* DOCUMENT animate
  228.          or animate, 0/1
  229.      without any arguments, toggles animation mode; with argument 0,
  230.      turns off animation mode, with argument 1 turns on animation mode.
  231.      In animation mode, the X window associated with a graphics window
  232.      is actually an offscreen pixmap which is bit-blitted onscreen
  233.      when an fma command is issued.  This is confusing unless you are
  234.      actually trying to make a movie, but results in smoother animation
  235.      if you are.  Generally, you should turn animation on, run your movie,
  236.      then turn it off.
  237.    SEE ALSO: window, fma, plg
  238.  */
  239.  
  240. extern plsys;
  241. /* DOCUMENT plsys, n
  242.      sets the current coordinate system to number N in the current
  243.      graphics window.  If N equals 0, subsequent elements will be
  244.      plotted in absolute NDC coordinates outside of any coordinate
  245.      system.  The default style sheet "work.gs" defines only a single
  246.      coordinate system, so the only other choice is N equal 1.  You
  247.      can make up your own style sheet (using a text editor) which
  248.      defines mulitple coordinate systems.  You need to do this if
  249.      you want to display four plots side by side on a single page,
  250.      for example.  The standard style sheets "work2.gs" and "boxed2.gs"
  251.      define two overlayed coordinate systems with the first labeled
  252.      to the right of the plot and the second labeled to the left of
  253.      the plot.  When using overlayed coordinate systems, it is your
  254.      responsibility to ensure that the x-axis limits in the two
  255.      systems are identical.
  256.    SEE ALSO: window, limits, plg
  257.  */
  258.  
  259. /*--------------------------------------------------------------------------*/
  260. /* Plotting functions (output primitives) */
  261.  
  262. extern plg;
  263. /* DOCUMENT plg, y, x
  264.          or plg, y
  265.      plots a graph of Y versus X.  Y and X must be 1-D arrays of equal
  266.      length; if X is omitted, it defaults to [1, 2, ..., numberof(Y)].
  267.      The following keywords are legal (each has a separate help entry):
  268.    KEYWORDS: legend, hide
  269.          type, width, color, closed, smooth
  270.              marks, marker, mspace, mphase
  271.          rays, arrowl, arroww, rspace, rphase
  272.    SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj
  273.              limits, logxy, range, fma, hcp
  274.  */
  275.  
  276. extern plm;
  277. /* DOCUMENT plm, y, x, boundary=0/1, inhibit=0/1/2
  278.          or plm, y, x, ireg, boundary=0/1, inhibit=0/1/2
  279.      or plm, boundary=0/1, inhibit=0/1/2
  280.      plots a mesh of Y versus X.  Y and X must be 2-D arrays with equal
  281.      dimensions.  If present, IREG must be a 2-D region number array
  282.      for the mesh, with the same dimensions as X and Y.  The values of
  283.      IREG should be positive region numbers, and zero for zones which do
  284.      not exist.  The first row and column of IREG never correspond to any
  285.      zone, and should always be zero.  The default IREG is 1 everywhere
  286.      else.  If present, the BOUNDARY keyword determines whether the
  287.      entire mesh is to be plotted (boundary=0, the default), or just the
  288.      boundary of the selected region (boundary=1).  If present, the
  289.      INHIBIT keyword causes the (X(,j),Y(,j)) lines to not be plotted
  290.      (inhibit=1), or the (X(i,),Y(i,)) lines to not be plotted (inhibit=2).
  291.      By default (inhibit=0), mesh lines in both logical directions are
  292.      plotted.
  293.      The Y, X, and IREG arguments may all be omitted to default to the
  294.      mesh set by the most recent plmesh call.
  295.      The following keywords are legal (each has a separate help entry):
  296.    KEYWORDS: legend, hide
  297.          type, width, color
  298.          region
  299.    SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj, plmesh
  300.              limits, logxy, range, fma, hcp
  301.  */
  302.  
  303. extern plmesh;
  304. /* DOCUMENT plmesh, y, x, ireg, triangle=tri_array
  305.          or plmesh
  306.      sets the default mesh for subsequent plm, plc, plv, and plf calls.
  307.      In the second form, deletes the default mesh (until you do this,
  308.      or switch to a new default mesh, the default mesh arrays persist and
  309.      take up space in memory).  The Y, X, and IREG arrays should all be
  310.      the same shape; Y and X will be converted to double, and IREG will
  311.      be converted to int.  If IREG is omitted, it defaults to IREG(1,)=
  312.      IREG(,1)= 0, IREG(2:,2:)=1; that is, region number 1 is the whole
  313.      mesh.  The triangulation array TRI_ARRAY is used by plc; the
  314.      correspondence between TRI_ARRAY indices and zone indices is the
  315.      same as for IREG, and its default value is all zero.
  316.      The IREG or TRI_ARRAY arguments may be supplied without Y and X
  317.      to change the region numbering or triangulation for a given set of
  318.      mesh coordinates.  However, a default Y and X must already have been
  319.      defined if you do this.
  320.      If Y is supplied, X must be supplied, and vice-versa.
  321.    SEE ALSO: plm, plc, plv, plf
  322.  */
  323.  
  324. extern plc;
  325. /* DOCUMENT plc, z, y, x, levs=z_values
  326.          or plc, z, y, x, ireg, levs=z_values
  327.      or plc, z, levs=z_values
  328.      plots a contours of Z on the mesh Y versus X.  Y, X, and IREG are
  329.      as for plm.  The Z array must have the same shape as Y and X.
  330.      The function being contoured takes the value Z at each point
  331.      (X,Y) -- that is, the Z array is presumed to be point-centered.
  332.      The Y, X, and IREG arguments may all be omitted to default to the
  333.      mesh set by the most recent plmesh call.
  334.      The LEVS keyword is a list of the values of Z at which you want
  335.      contour curves.  The default is eight contours spanning the
  336.      range of Z.
  337.      The following keywords are legal (each has a separate help entry):
  338.    KEYWORDS: legend, hide
  339.          type, width, color, smooth
  340.              marks, marker, mspace, mphase
  341.          smooth, triangle, region
  342.    SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj, plmesh
  343.              limits, logxy, range, fma, hcp
  344.  */
  345.  
  346. extern plv;
  347. /* DOCUMENT plv, v, u, y, x, scale=dt
  348.          or plv, v, u, y, x, ireg, scale=dt
  349.      or plv, v, u, scale=dt
  350.      plots a vector field (U,V) on the mesh (X,Y).  Y, X, and IREG are
  351.      as for plm.  The V and U arrays must have the same shape as Y and X.
  352.      The Y, X, and IREG arguments may all be omitted to default to the
  353.      mesh set by the most recent plmesh call.
  354.      The SCALE keyword is the conversion factor from the units of
  355.      (U,V) to the units of (X,Y) -- a time interval if (U,V) is a velocity
  356.      and (X,Y) is a position -- which determines the length of the
  357.      vector "darts" plotted at the (X,Y) points.  If omitted, SCALE is
  358.      chosen so that the longest ray arrows have a length comparable
  359.      to a "typical" zone size.
  360.      You can use the scalem keyword in pledit to make adjustments to the
  361.      SCALE factor computed by default.
  362.      The following keywords are legal (each has a separate help entry):
  363.    KEYWORDS: legend, hide
  364.          type, width, color, smooth
  365.              marks, marker, mspace, mphase
  366.          triangle, region
  367.    SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj, plmesh, pledit,
  368.              limits, logxy, range, fma, hcp
  369.  */
  370.  
  371. extern plf;
  372. /* DOCUMENT plf, z, y, x
  373.          or plf, z, y, x, ireg
  374.      or plf, z
  375.      plots a filled mesh Y versus X.  Y, X, and IREG are as for plm.
  376.      The Z array must have the same shape as Y and X, or one smaller
  377.      in both dimensions.  If Z is of type char, it is used "as is",
  378.      otherwise it is linearly scaled to fill the current palette, as
  379.      with the bytscl function.
  380.      (See the bytscl function for explanation of top, cmin, cmax.)
  381.      The mesh is drawn with each zone in the color derived from the Z
  382.      function and the current palette; thus Z is interpreted as a
  383.      zone-centered array.
  384.      The Y, X, and IREG arguments may all be omitted to default to the
  385.      mesh set by the most recent plmesh call.
  386.      A solid edge can optionally be drawn around each zone by setting
  387.      the EDGES keyword non-zero.  ECOLOR and EWIDTH determine the edge
  388.      color and width.  The mesh is drawn zone by zone in order from
  389.      IREG(2+imax) to IREG(jmax*imax) (the latter is IREG(imax,jmax)),
  390.      so you can achieve 3D effects by arranging for this order to
  391.      coincide with back-to-front order.  If Z is nil, the mesh zones
  392.      are filled with the background color, which you can use to
  393.      produce 3D wire frames.
  394.      The following keywords are legal (each has a separate help entry):
  395.    KEYWORDS: legend, hide
  396.          region, top, cmin, cmax, edges, ecolor, ewidth
  397.    SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj, plmesh,
  398.              limits, logxy, range, fma, hcp, palette, bytscl, histeq_scale
  399.  */
  400.  
  401. extern pli;
  402. /* DOCUMENT pli, z
  403.          or pli, z, x1, y1
  404.          or pli, z, x0, y0, x1, y1
  405.      plots the image Z as a cell array -- an array of equal rectangular
  406.      cells colored according to the 2-D array Z.  The first dimension
  407.      of Z is plotted along x, the second dimension is along y.
  408.      If Z is of type char, it is used "as is", otherwise it is linearly
  409.      scaled to fill the current palette, as with the bytscl function.
  410.      (See the bytscl function for explanation of top, cmin, cmax.)
  411.      If X1 and Y1 are given, they represent the coordinates of the
  412.      upper right corner of the image.  If X0, and Y0 are given, they
  413.      represent the coordinates of the lower left corner, which is at
  414.      (0,0) by default.  If only the Z array is given, each cell will be
  415.      a 1x1 unit square, with the lower left corner of the image at (0,0).
  416.      The following keywords are legal (each has a separate help entry):
  417.    KEYWORDS: legend, hide, top, cmin, cmax
  418.    SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj,
  419.              limits, logxy, range, fma, hcp, palette, bytscl, histeq_scale
  420.  */
  421.  
  422. extern pldj;
  423. /* DOCUMENT pldj, x0, y0, x1, y1
  424.      plots disjoint lines from (X0,Y0) to (X1,Y1).  X0, Y0, X1, and Y1
  425.      may have any dimensionality, but all must have the same number of
  426.      elements.
  427.      The following keywords are legal (each has a separate help entry):
  428.    KEYWORDS: legend, hide
  429.          type, width, color
  430.    SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj
  431.              limits, logxy, range, fma, hcp
  432.  */
  433.  
  434. extern plt;
  435. /* DOCUMENT plt, text, x, y, tosys=0/1
  436.      plots TEXT (a string) at the point (X,Y).  The exact relationship
  437.      between the point (X,Y) and the TEXT is determined by the
  438.      justify keyword.  TEXT may contain newline ("\n") characters
  439.      to output multiple lines of text with a single call.  The
  440.      coordinates (X,Y) are NDC coordinates (outside of any coordinate
  441.      system) unless the tosys keyword is present and non-zero, in
  442.      which case the TEXT will be placed in the current coordinate
  443.      system.  However, the character height is NEVER affected by the
  444.      scale of the coordinate system to which the text belongs.
  445.      Note that the pledit command takes dx and/or dy keywords to
  446.      adjust the position of existing text elements.
  447.      The following keywords are legal (each has a separate help entry):
  448.    KEYWORDS: legend, hide
  449.          color, font, height, opaque, path, justify
  450.    SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj, pledit
  451.              limits, range, fma, hcp, pltitle
  452.  */
  453.  
  454. func pltitle(title)
  455. /* DOCUMENT pltitle, title
  456.      Plot TITLE centered above the coordinate system for any of the
  457.      standard Gist styles.  You will need to customize this for other
  458.      plot styles.
  459.  */
  460. {
  461.   plt, title, 0.395, 0.870, font="helvetica", justify="CA", height=18;
  462. }
  463.  
  464. /*--------------------------------------------------------------------------*/
  465. /* Plot limits and log/linear scaling */
  466.  
  467. e= "e";         /* for use with limits and range functions */
  468.  
  469. extern limits;
  470. /* DOCUMENT limits
  471.          or limits, xmin, xmax, ymin, ymax,
  472.                 square=0/1, nice=0/1, restrict=0/1
  473.      or old_limits= limits()
  474.      or limits, old_limits
  475.  
  476.      In the first form, restores all four plot limits to extreme values.
  477.  
  478.      In the second form, sets the plot limits in the current coordinate
  479.      system to XMIN, XMAX, YMIN, YMAX, which may be nil or omitted to
  480.      leave the corresponding limit unchanged, a number to fix the
  481.      corresponding limit to a specified value, or the string "e" to
  482.      make the corresponding limit take on the extreme value of the
  483.      currently displayed data.
  484.  
  485.      If present, the square keyword determines whether limits marked
  486.      as extreme values will be adjusted to force the x and y scales
  487.      to be equal (square=1) or not (square=0, the default).
  488.      If present, the nice keyword determines whether limits will be
  489.      adjusted to nice values (nice=1) or not (nice=0, the default).
  490.      There is a subtlety in the meaning of "extreme value" when one
  491.      or both of the limits on the OPPOSITE axis have fixed values --
  492.      does the "extreme value" of the data include points which
  493.      will not be plotted because their other coordinate lies outside
  494.      the fixed limit on the opposite axis (restrict=0, the default),
  495.      or not (restrict=1)?
  496.  
  497.      If called as a function, limits returns an array of 5 doubles;
  498.      OLD_LIMITS(1:4) are the current xmin, xmax, ymin, and ymax,
  499.      and int(OLD_LIMITS(5)) is a set of flags indicating extreme
  500.      values and the square, nice, restrict, and log flags.
  501.  
  502.      In the fourth form, OLD_LIMITS is as returned by a previous
  503.      limits call, to restore the limits to a previous state.
  504.  
  505.      In an X window, the limits may also be adjusted interactively
  506.      with the mouse.  Drag left to zoom in and pan (click left to zoom
  507.      in on a point without moving it), drag middle to pan, and click
  508.      (and drag) right to zoom out (and pan).  If you click just above
  509.      or below the plot, these operations will be restricted to the
  510.      x-axis; if you click just to the left or right, the operations
  511.      are restricted to the y-axis.  A shift-left click, drag, and
  512.      release will expand the box you dragged over to fill the plot
  513.      (other popular software zooms with this paradigm).  If the
  514.      rubber band box is not visible with shift-left zooming, try
  515.      shift-middle or shift-right for alternate XOR masks.  Such
  516.      mouse-set limits are equivalent to a limits command specifying
  517.      all four limits EXCEPT that the unzoom command can revert to
  518.      the limits before a series of mouse zooms and pans.
  519.  
  520.      The limits you set using the limits or range functions carry over
  521.      to the next plot -- that is, an fma operation does NOT reset the
  522.      limits to extreme values.
  523.  
  524.    SEE ALSO: plsys, range, logxy, zoom_factor, unzoom, plg
  525.  */
  526.  
  527. func range(ymin, ymax) { limits,,, ymin, ymax; }
  528. /* DOCUMENT range, ymin, ymax
  529.      sets the y-axis plot limits in the current coordinate system to
  530.      YMIN, YMAX, which may be nil or omitted to leave the corresponding
  531.      limit unchanged, a number to fix the corresponding limit to a
  532.      specified value, or the string "e" to make the corresponding limit
  533.      take on the extreme value of the currently displayed data.
  534.      Use    limits, xmin, xmin
  535.      to accomplish the same function for the x-axis plot limits.
  536.    SEE ALSO: plsys, limits, logxy, plg
  537.  */
  538.  
  539. extern logxy;
  540. /* DOCUMENT logxy, xflag, yflag
  541.      sets the linear/log axis scaling flags for the current coordinate
  542.      system.  XFLAG and YFLAG may be nil or omitted to leave the
  543.      corresponding axis scaling unchanged, 0 to select linear scaling,
  544.      or 1 to select log scaling.
  545.    SEE ALSO: plsys, limits, range, plg, gridxy
  546.  */
  547.  
  548. extern gridxy;
  549. /* DOCUMENT gridxy, flag
  550.          or gridxy, xflag, yflag
  551.      Turns on or off grid lines according to FLAG.  In the first form, both
  552.      the x and y axes are affected.  In the second form, XFLAG and YFLAG
  553.      may differ to have different grid options for the two axes.  In either
  554.      case, a FLAG value of 0 means no grid lines (the default), a value of
  555.      1 means grid lines at all major ticks (the level of ticks which get
  556.      grid lines can be set in the style sheet), and a FLAG value of 2 means
  557.      that the coordinate origin only will get a grid line.  In styles with
  558.      multiple coordinate systems, only the current coordinate system is
  559.      affected.
  560.      The keywords can be used to affect the style of the grid lines.
  561.    KEYWORDS: color, type, width
  562.    SEE ALSO: window, plsys, limits, range, logxy
  563.  */
  564.  
  565. extern zoom_factor;
  566. /* DOCUMENT zoom_factor, factor
  567.      sets the zoom factor for mouse-click zoom in and zoom out operations.
  568.      The default FACTOR is 1.5; FACTOR should always be greater than 1.0.
  569.    SEE ALSO: limits, range, unzoom, plg
  570.  */
  571.  
  572. extern unzoom;
  573. /* DOCUMENT unzoom
  574.      restores limits to their values before zoom and pan operations
  575.      performed interactively using the mouse.
  576.      Use    old_limits=  limits()
  577.             ...
  578.         limits, old_limits
  579.      to save and restore plot limits generally.
  580.    SEE ALSO: limits, range, zoom_factor, plg
  581.  */
  582.  
  583. /*--------------------------------------------------------------------------*/
  584. /* Keywords for plotting functions */
  585.  
  586. local legend;
  587. /* DOCUMENT legend=   plotting keyword
  588.      sets the legend for a plot.  The default legend is a concatentation
  589.      of the strings used in the original plotting command (plg, plm, etc.),
  590.      except for the plt command, which has no default legend.
  591.      Legends are never plotted to the X window; use the plq command to
  592.      see them interactively.  Legends will appear in hardcopy output
  593.      unless they have been explicitly turned off.
  594.    PLOTTING COMMANDS: plg, plm, plc, plv, plf, pli, plt, pldj
  595.    SEE ALSO: hide
  596.  */
  597.  
  598. local hide;
  599. /* DOCUMENT hide=   plotting keyword
  600.      sets the visibility of a plotted element.  The default is hide=0,
  601.      which means that the element will be visible.  Use hide=1 to remove
  602.      the element from the plot (but not from the display list).
  603.    PLOTTING COMMANDS: plg, plm, plc, plv, plf, pli, plt, pldj
  604.    SEE ALSO: legend
  605.  */
  606.  
  607. local type;
  608. /* DOCUMENT type=   plotting keyword
  609.      selects line type.  Valid values are the strings "solid", "dash",
  610.      "dot", "dashdot", "dashdotdot", and "none".  The "none" value
  611.      causes the line to be plotted as a polymarker.
  612.      The type value may also be a number; 0 is "none", 1 is "solid",
  613.      2 is "dash", 3 is "dot", 4 is "dashdot", and 5 is "dashdotdot".
  614.    PLOTTING COMMANDS: plg, plm, plc, pldj
  615.    SEE ALSO: width, color, marks, marker, rays, closed, smooth
  616.  */
  617.  
  618. local width;
  619. /* DOCUMENT width=   plotting keyword
  620.      selects line width.  Valid values are positive floating point numbers
  621.      giving the line thickness relative to the default line width of one
  622.      half point, width= 1.0.
  623.    PLOTTING COMMANDS: plg, plm, plc, pldj, plv (only if hollow=1)
  624.    SEE ALSO: type, color, marks, marker, rays, closed, smooth
  625.  */
  626.  
  627. local color;
  628. /* DOCUMENT color=   plotting keyword
  629.      selects line or text color.  Valid values are the strings "bg", "fg",
  630.      "black", "white", "red", "green", "blue", "cyan", "magenta", "yellow",
  631.      or a 0-origin index into the current palette.  The default is "fg".
  632.      Negative numbers may be used instead of the strings: -1 is bg
  633.      (background), -2 is fg (foreground), -3 is black, -4 is white,
  634.      -5 is red, -6 is green, -7 is blue, -8 is cyan, -9 is magenta, and
  635.      -10 is yellow.
  636.    PLOTTING COMMANDS: plg, plm, plc, pldj, plt
  637.    SEE ALSO: type, width, marks, marker, mcolor, rays, closed, smooth
  638.  */
  639.  
  640. local marks;
  641. /* DOCUMENT marks=   plotting keyword
  642.      selects unadorned lines (marks=0), or lines with occasional markers
  643.      (marks=1).  Ignored if type is "none" (indicating polymarkers instead
  644.      of occasional markers).  The spacing and phase of the occasional
  645.      markers can be altered using the mspace and mphase keywords; the
  646.      character used to make the mark can be altered using the marker
  647.      keyword.
  648.    PLOTTING COMMANDS: plg, plc
  649.    SEE ALSO: type, width, color, marker, rays, mspace, mphase, msize, mcolor
  650.  */
  651.  
  652. local marker;
  653. /* DOCUMENT marker=   plotting keyword
  654.      selects the character used for occasional markers along a polyline,
  655.      or for the polymarker if type is "none".  The special values
  656.      '\1', '\2', '\3', '\4', and '\5' stand for point, plus, asterisk,
  657.      circle, and cross, which are prettier than text characters on output
  658.      to some devices.  The default marker is the next available capital
  659.      letter, 'A', 'B', ..., 'Z'.
  660.    PLOTTING COMMANDS: plg, plc
  661.    SEE ALSO: type, width, color, marks, rays, mspace, mphase, msize, mcolor
  662.  */
  663.  
  664. local mspace, mphase, msize, mcolor;
  665. /* DOCUMENT mspace=   plotting keyword
  666.          or mphase=   plotting keyword
  667.          or msize=    plotting keyword
  668.          or mcolor=   plotting keyword
  669.      selects the spacing, phase, and size of occasional markers placed
  670.      along polylines.  The msize also selects polymarker size if type
  671.      is "none".  The spacing and phase are in NDC units (0.0013 NDC
  672.      equals 1.0 point); the default mspace is 0.16, and the default
  673.      mphase is 0.14, but mphase is automatically incremented for
  674.      successive curves on a single plot.  The msize is in relative
  675.      units, with the default msize of 1.0 representing 10 points.
  676.      The mcolor keyword is the same as the color keyword, but controls
  677.      the marker color instead of the line color.  Setting the color
  678.      automatically sets the mcolor to the same value, so you only
  679.      need to use mcolor if you want the markers for a curve to be a
  680.      different color than the curve itself.
  681.    PLOTTING COMMANDS: plg, plc
  682.    SEE ALSO: type, width, color, marks, marker, rays
  683.  */
  684.  
  685. local rays;
  686. /* DOCUMENT rays=   plotting keyword
  687.      selects unadorned lines (rays=0), or lines with occasional ray
  688.      arrows (rays=1).  Ignored if type is "none".  The spacing and phase
  689.      of the occasional arrows can be altered using the rspace and rphase
  690.      keywords; the shape of the arrowhead can be modified using the
  691.      arroww and arrowl keywords.
  692.    PLOTTING COMMANDS: plg, plc
  693.    SEE ALSO: type, width, color, marker, marks, rspace, rphase
  694.              arroww, arrowl
  695.  */
  696.  
  697. local rspace, rphase, arroww, arrowl;
  698. /* DOCUMENT rspace=   plotting keyword
  699.          or rphase=   plotting keyword
  700.          or arroww=   plotting keyword
  701.          or arrowl=   plotting keyword
  702.      selects the spacing, phase, and size of occasional ray arrows
  703.      placed along polylines.  The spacing and phase are in NDC units
  704.      (0.0013 NDC equals 1.0 point); the default rspace is 0.13, and
  705.      the default rphase is 0.11375, but rphase is automatically
  706.      incremented for successive curves on a single plot.
  707.      The arrowhead width, arroww, and arrowhead length, arrowl are
  708.      in relative units, defaulting to 1.0, which translates to an
  709.      arrowhead 10 points long and 4 points in half-width.
  710.    PLOTTING COMMANDS: plg
  711.    SEE ALSO: type, width, color, marks, marker, rays
  712.  */
  713.  
  714. local closed, smooth;
  715. /* DOCUMENT closed=   plotting keyword
  716.          or smooth=   plotting keyword
  717.      selects closed curves (closed=1) or default open curves (closed=0),
  718.      or Bezier smoothing (smooth>0) or default piecewise linear curves
  719.      (smooth=0).  The value of smooth can be 1, 2, 3, or 4 to get
  720.      successively more smoothing.  Only the Bezier control points are
  721.      plotted to an X window; the actual Bezier curves will show up in
  722.      PostScript hardcopy files.  Closed curves join correctly, which
  723.      becomes more noticeable for wide lines; non-solid closed curves
  724.      may look bad because the dashing pattern may be incommensurate
  725.      with the length of the curve.
  726.    PLOTTING COMMANDS: plg, plc (smooth only)
  727.    SEE ALSO: type, width, color, marks, marker, rays
  728.  */
  729.  
  730. local font, height, opaque, path, justify;
  731. /* DOCUMENT font=     plotting keyword
  732.          or height=   plotting keyword
  733.          or opaque=   plotting keyword
  734.          or path=     plotting keyword
  735.          or justify=  plotting keyword
  736.      selects text properties.  The font can be any of the strings
  737.      "courier", "times", "helvetica" (the default), "symbol", or
  738.      "schoolbook".  Append "B" for boldface and "I" for italic, so
  739.      "courierB" is boldface Courier, "timesI" is Times italic, and
  740.      "helveticaBI" is bold italic (oblique) Helvetica.  Your X server
  741.      should have the Adobe fonts (available free from the MIT X
  742.      distribution tapes) for all these fonts, preferably at both 75
  743.      and 100 dpi.  Occasionally, a PostScript printer will not be
  744.      equipped for some fonts; often New Century Schoolbook is missing.
  745.      The font keyword may also be an integer: 0 is Courier, 4 is Times,
  746.      8 is Helvetica, 12 is Symbol, 16 is New Century Schoolbook, and
  747.      you add 1 to get boldface and/or 2 to get italic (or oblique).
  748.  
  749.      The height is the font size in points; 14.0 is the default.
  750.      X windows only has 8, 10, 12, 14, 18, and 24 point fonts, so
  751.      don't stray from these sizes if you want what you see on the
  752.      screen to be a reasonably close match to what will be printed.
  753.  
  754.      By default, opaque=0 and text is transparent.  Set opaque=1 to
  755.      white-out a box before drawing the text.  The default path
  756.      (path=0) is left-to-right text; set path=1 for top-to-bottom text.
  757.  
  758.      The default text justification, justify="NN" is normal is both
  759.      the horizontal and vertical directions.  Other possibilities
  760.      are "L", "C", or "R" for the first character, meaning left,
  761.      center, and right horizontal justification, and "T", "C", "H",
  762.      "A", or "B", meaning top, capline, half, baseline, and bottom
  763.      vertical justification.  The normal justification "NN" is equivalent
  764.      to "LA" if path=0, and to "CT" if path=1.  Common values are
  765.      "LA", "CA", and "RA" for garden variety left, center, and right
  766.      justified text, with the y coordinate at the baseline of the
  767.      last line in the string presented to plt.  The characters labeling
  768.      the right axis of a plot are "RH", so that the y value of the
  769.      text will match the y value of the corresponding tick.  Similarly,
  770.      the characters labeling the bottom axis of a plot are "CT".
  771.      The justification may also be a number, horizontal+vertical,
  772.      where horizontal is 0 for "N", 1 for "L", 2 for "C", or 3 for "R",
  773.      and vertical is 0 for "N", 4 for "T", 8 for "C", 12 for "H",
  774.      16 for "A", or 20 for "B".
  775.  
  776.    PLOTTING COMMANDS: plt
  777.    SEE ALSO: color
  778.  */
  779.  
  780. local region;
  781. /* DOCUMENT region=   plotting keyword
  782.      selects the part of mesh to consider.  The region should match one
  783.      of the numbers in the IREG array.  Putting region=0 (the default)
  784.      means to plot the entire mesh, that is, everything EXCEPT region
  785.      zero (non-existent zones).  Any other number means to plot only
  786.      the specified region number; region=3 would plot region 3 only.
  787.    PLOTTING COMMANDS: plm, plc, plv, plf
  788.  */
  789.  
  790. local triangle;
  791. /* DOCUMENT triangle=   plotting keyword
  792.      sets the triangulation array for a contour plot.  The triangulation
  793.      array must be the same shape as the IREG (region number) array, and
  794.      the correspondence between mesh zones and indices is the same as
  795.      for IREG.  The triangulation array is used to resolve the ambiguity
  796.      in saddle zones, in which the function Z being contoured has two
  797.      diagonally opposite corners high, and the other two corners low.
  798.      The triangulation array element for a zone is 0 if the algorithm is
  799.      to choose a triangulation, based on the curvature of the first
  800.      contour to enter the zone.  If zone (i,j) is to be triangulated
  801.      from point (i-1,j-1) to point (i,j), then TRIANGLE(i,j)=1,
  802.      while if it is to be triangulated from (i-1,j) to (i,j-1), then
  803.      TRIANGLE(i,j)=-1.  Contours will never cross this "triangulation
  804.      line".
  805.      You should rarely need to fiddle with the traingulation array;
  806.      it is a hedge for dealing with pathological cases.
  807.    PLOTTING COMMANDS: plc
  808.  */
  809.  
  810. local hollow, aspect;
  811. /* DOCUMENT hollow=   plotting keyword
  812.          or aspect=   plotting keyword
  813.      set the appearance of the "darts" of a vector field plot.  The
  814.      default darts, hollow=0, are filled; use hollow=1 to get just the
  815.      dart outlines.  The default is aspect=0.125; aspect is the ratio
  816.      of the half-width to the length of the darts.  Use the color
  817.      keyword to control the color of the darts.
  818.    PLOTTING COMMANDS: plv
  819.    SEE ALSO: color
  820.  */
  821.  
  822. local edges, ecolor, ewidth;
  823. /* DOCUMENT edges=   plotting keyword
  824.          or ecolor=   plotting keyword
  825.          or ewidth=   plotting keyword
  826.      set the appearance of the zone edges in a filled mesh plot (plf).
  827.      By default, edges=0, and the zone edges are not plotted.  If
  828.      edges=1, a solid line is drawn around each zone after it is
  829.      filled; the edge color and width are given by ecolor and ewidth,
  830.      which are "fg" and 1.0 by default.
  831.    PLOTTING COMMANDS: plf
  832.    SEE ALSO: color, width
  833.  */
  834.  
  835. /*--------------------------------------------------------------------------*/
  836. /* Inquiry and editing functions */
  837.  
  838. extern plq;
  839. /* DOCUMENT plq
  840.          or plq, n_element
  841.      or plq, n_element, n_contour
  842.      or legend_list= plq()
  843.      or properties= plq(n_element, n_contour)
  844.      Called as a subroutine, prints the list of legends for the current
  845.      coordinate system (with an "(H)" to mark hidden elements), or prints
  846.      a list of current properties of element N_ELEMENT (such as line type,
  847.      width, font, etc.), or of contour number N_CONTOUR of element number
  848.      N_ELEMENT (which must be contours generated using the plc command).
  849.      Called as a function, returns either the list of legend strings, or a
  850.      list of pointers to the values of the various element properties.
  851.      Elements and contours are both numbered starting with one; hidden
  852.      elements or contours are included in this numbering.
  853.  
  854.      The PROPERTIES list returned by plq is a list of pointers to the
  855.      relevent properties for the specified graphical element.  Each
  856.      possible property has a particular index in the returned PROPERTIES
  857.      list as follows:
  858.      *PROPERTIES(1)   int([element type (0 for none, 1 for plg, 2 for pldj,
  859.                                          3 for plt, 4 for plm, 5 for plf,
  860.                      6 for plv, 7 for plc, 8 for pli),
  861.                            hide flag])
  862.      *PROPERTIES(2)   string(legend)
  863.      *PROPERTIES(3)   int array, depends on type (names match keywords):
  864.        1 plg:  [color, type, marks, mcolor, marker, rays, closed, smooth]
  865.        2 pldj: [color, type]
  866.        3 plt:  [color, font, path, justify, opaque]
  867.        4 plm:  [color, type, region, boundary, inhibit]
  868.        5 plf:  [region, edges, ecolor]
  869.        6 plv:  [region, color, hollow]
  870.        7 plc:  [region, color, type, marks, mcolor, marker, smooth]
  871.        8 pli:  nil
  872.      *PROPERTIES(4)   double array, depends on type (names match keywords):
  873.        1 plg:  [width, msize, mspace, mphase, rspace, rphase, arrowl, arroww]
  874.        2 pldj: [width]
  875.        3 plt:  [height, x, y]
  876.        4 plm:  [width]
  877.        5 plf:  [ewidth]
  878.        6 plv:  [width, aspect, scale]
  879.        7 plc:  [width, msize, mspace, mphase]
  880.        8 pli:  [x0, x1, y0, y1]
  881.      *PROPERTIES(5)   long array, depends on type (names match arguments):
  882.        1 plg:  [npoints, &x, &y]
  883.        2 pldj: [npoints, &x0, &y0, &x1, &y1]
  884.        3 plt:  [nchars, &text]
  885.        4 plm:  [imax, jmax, &x, &y, &ireg]
  886.        5 plf:  [imax, jmax, &x, &y, &ireg, &colors]
  887.        6 plv:  [imax, jmax, &x, &y, &ireg, &u, &v]
  888.        7 plc:  [imax, jmax, &x, &y, &ireg, &z, &triangle, nlevs, &levs]
  889.        8 pli:  [imax, jmax, &colors]
  890.      You can use the reshape function to peek at the data at the addresses
  891.      returned in PROPERTIES(5) as longs.  The appropriate data types are:
  892.      char for text, int for ireg, short for triangle, char for colors, and
  893.      double for everything else.  In a plf, colors is (imax-1)-by-(jmax-1).
  894.      Although PROPERTIES(5) returns pointers to the data plotted, attempting
  895.      to poke new values into this data will not produce immediate changes
  896.      to your plot, since the graphics package does not realize that anything
  897.      has changed.  Use pledit to make changes to plotted elements.
  898.  
  899.      The plq function always operates on the current coordinate system
  900.      in the current graphics window; use window and plsys to change these.
  901.    SEE ALSO: window, plsys, pledit, pldefault, plg
  902.  */
  903.  
  904. extern pledit;
  905. /* DOCUMENT pledit, key1=value1, key2=value2, ...
  906.          or pledit, n_element, key1=value1, key2=value2, ...
  907.          or pledit, n_element, n_contour, key1=value1, key2=value2, ...
  908.      changes some property of element number N_ELEMENT (and contour
  909.      number N_CONTOUR of that element).  If N_ELEMENT and N_CONTOUR are
  910.      omitted, the default is the most recently added element, or the
  911.      element specified in the most recent plq query command.
  912.  
  913.      The keywords can be any of the keywords that apply to the current
  914.      element.  These are:
  915.        plg:  color, type, width,
  916.              marks, mcolor, marker, msize, mspace, mphase,
  917.          rays, rspace, rphase, arrowl, arroww,
  918.          closed, smooth
  919.        pldj: color, type, width
  920.        plt:  color, font, height, path, justify, opaque
  921.        plm:  region, boundary, inhibit, color, type, width
  922.        plf:  region
  923.        plv:  region, color, hollow, width, aspect, scale
  924.        plc:  region, color, type, width,
  925.              marks, mcolor, marker, msize, mspace, mphase
  926.          smooth, levs
  927.      (For contours, if you aren't talking about a particular N_CONTOUR,
  928.       any changes will affect ALL the contours.)
  929.  
  930.      A plv (vector field) element can also take the scalem
  931.      keyword to multiply all vector lengths by a specified factor.
  932.  
  933.      A plt (text) element can also take the dx and/or dy
  934.      keywords to adjust the text position by (dx,dy).
  935.  
  936.    SEE ALSO: window, plsys, plq, pldefault, plg
  937.  */
  938.  
  939. extern pldefault;
  940. /* DOCUMENT pldefault, key1=value1, key2=value2, ...
  941.      sets default values for the various properties of graphical elements.
  942.  
  943.      The keywords can be most of the keywords that can be passed to the
  944.      plotting commands:
  945.        plg:  color, type, width,
  946.              marks, mcolor, msize, mspace, mphase,
  947.          rays, rspace, rphase, arrowl, arroww
  948.        pldj: color, type, width
  949.        plt:  color, font, height, path, justify, opaque
  950.        plm:  color, type, width
  951.        plv:  color, hollow, width, aspect
  952.        plc:  color, type, width,
  953.              marks, mcolor, marker, msize, mspace, mphase
  954.        plf:  edges, ecolor, ewidth
  955.  
  956.      The initial default values are:
  957.        color="fg", type="solid", width=1.0 (1/2 point),
  958.        marks=1, mcolor="fg", msize=1.0 (10 points),
  959.           mspace=0.16, mphase=0.14,
  960.        rays=0, arrowl=1.0 (10 points), arroww=1.0 (4 points),
  961.           rspace=0.13, rphase=0.11375,
  962.        font="helvetica", height=12.0, path=0, justify="NN", opaque=0,
  963.        hollow= 0, aspect=0.125,
  964.        edges=0, ecolor="fg", ewidth=1.0 (1/2 point)
  965.  
  966.      Additional default keywords are:
  967.        dpi, style, legends  (see window command)
  968.        palette              (to set default filename as in palette command)
  969.        maxcolors            (default 200)
  970.  
  971.    SEE ALSO: window, plsys, plq, pledit, plg
  972.  */
  973.  
  974. /*--------------------------------------------------------------------------*/
  975. /* Miscellany */
  976.  
  977. extern bytscl;
  978. /* DOCUMENT bytscl(z)
  979.          or bytscl(z, top=max_byte, cmin=lower_cutoff, cmax=upper_cutoff)
  980.      returns a char array of the same shape as Z, with values linearly
  981.      scaled to the range 0 to one less than the current palette size.
  982.      If MAX_BYTE is specified, the scaled values will run from 0 to
  983.      MAX_BYTE instead.
  984.      If LOWER_CUTOFF and/or UPPER_CUTOFF are specified, Z values outside
  985.      this range are mapped to the cutoff value; otherwise the linear
  986.      scaling maps the extreme values of Z to 0 and MAX_BYTE.
  987.    SEE ALSO: plf, pli, histeq_scale
  988.  */
  989.  
  990. extern mesh_loc;
  991. /* DOCUMENT mesh_loc(y0, x0)
  992.          or mesh_loc(y0, x0, y, x)
  993.          or mesh_loc(y0, x0, y, x, ireg)
  994.      returns the zone index (=i+imax*(j-1)) of the zone of the mesh
  995.      (X,Y) (with optional region number array IREG) containing the
  996.      point (X0,Y0).  If (X0,Y0) lies outside the mesh, returns 0.
  997.      Thus, eg- ireg(mesh_loc(x0, y0, y, x, ireg)) is the region number of
  998.      the region containing (x0,y0).  If no mesh specified, uses default.
  999.      X0 and Y0 may be arrays as long as they are conformable.
  1000.    SEE ALSO: plmesh, moush, mouse
  1001.  */
  1002.  
  1003. extern mouse;
  1004. /* DOCUMENT result= mouse(system, style, prompt)
  1005.      displays a PROMPT, then waits for a mouse button to be pressed,
  1006.      then released.  Returns array of eleven doubles:
  1007.        result= [x_pressed, y_pressed, x_released, y_released,
  1008.                 xndc_pressed, yndc_pressed, xndc_released, yndc_released,
  1009.             system, button, modifiers]
  1010.  
  1011.      If SYSTEM>=0, the first four coordinate values will be relative to
  1012.      that coordinate system.
  1013.      For SYSTEM<0, the first four coordinate values will be relative to
  1014.      the coordinate system under the mouse when the button was pressed.
  1015.      The second four coordinates are always normalized device coordinates,
  1016.      which start at (0,0) in the lower left corner of the 8.5x11 sheet of
  1017.      paper the picture will be printed on, with 0.0013 NDC unit being
  1018.      1/72.27 inch (1.0 point).  Look in the style sheet for the location
  1019.      of the viewport in NDC coordinates (see the style keyword).
  1020.  
  1021.      If STYLE is 0, there will be no visual cues that the mouse
  1022.      command has been called; this is intended for a simple click.
  1023.      If STYLE is 1, a rubber band box will be drawn; if STYLE is 2,
  1024.      a rubber band line will be drawn.  These disappear when the
  1025.      button is released.
  1026.  
  1027.      Clicking a second button before releasing the first cancels the
  1028.      mouse function, which will then return nil.
  1029.      Ordinary text input also cancels the mouse function, which again
  1030.      returns nil.
  1031.  
  1032.      The left button reverses forground for background (by XOR) in
  1033.      order to draw the rubber band (if any).  The middle and right
  1034.      buttons use other masks, in case the rubber band is not visible
  1035.      with the left button.
  1036.  
  1037.      long(result(9)) is the coordinate system in which the first four
  1038.      coordinates are to be interpreted.
  1039.      long(result(10)) is the button which was pressed, 1 for left, 2
  1040.      for middle, and 3 for right (4 and 5 are also possible).
  1041.      long(result(11)) is a mask representing the modifier keys which
  1042.      were pressed during the operation: 1 for shift, 2 for shift lock,
  1043.      4 for control, 8 for mod1 (alt or meta), 16 for mod2, 32 for mod3,
  1044.      64 for mod4, and 128 for mod5.
  1045.  
  1046.    SEE ALSO: moush
  1047.  */
  1048.  
  1049. func moush(y, x, ireg)
  1050. /* DOCUMENT moush()
  1051.          or moush(y, x, ireg)
  1052.      returns the 1-origin zone index for the point clicked in
  1053.      for the default mesh, or for the mesh (X,Y) (region array IREG).
  1054.  */
  1055. {
  1056.   xy= mouse(-1, 0, "<Click mouse in mesh>");
  1057.   if (is_void(xy)) return [];
  1058.   else return mesh_loc(xy(2), xy(1), y, x, ireg);
  1059. }
  1060.  
  1061. extern pause;
  1062. /* DOCUMENT pause, milliseconds
  1063.      pause for the specified number of milliseconds of wall clock
  1064.      time, or until input arrives from the keyboard.
  1065.      This is intended for use in creating animated sequences.
  1066.  */
  1067.  
  1068. /*--------------------------------------------------------------------------*/
  1069.  
  1070. func histeq_scale(z, top=, cmin=, cmax=)
  1071. /* DOCUMENT histeq_scale(z, top=top_value, cmin=cmin, cmax=cmax)
  1072.      returns a byte-scaled version of the array Z having the property
  1073.      that each byte occurs with equal frequency (Z is histogram
  1074.      equalized).  The result bytes range from 0 to TOP_VALUE, which
  1075.      defaults to one less than the size of the current palette (or
  1076.      255 if no pli, plf, or palette command has yet been issued).
  1077.  
  1078.      If non-nil CMIN and/or CMAX is supplied, values of Z beyond these
  1079.      cutoffs are not included in the frequency counts.
  1080.  
  1081.    SEE ALSO: bytscl, plf, pli
  1082.  */
  1083. {
  1084.   if (is_void(top)) top= bytscl([0.,1.])(2);  /* palette size - 1 */
  1085.   top= long(top);
  1086.   if (top<0 | top>255) error, "top value out of range 0-255";
  1087.   y= z(*);
  1088.   if (!is_void(cmin)) y= y(where(y>=cmin));
  1089.   if (!is_void(cmax)) y= y(where(y<=cmax));
  1090.   y= y(sort(y));
  1091.   x= span(0.,1., numberof(y));
  1092.   xp= span(0.,1., top+2);
  1093.   bins= interp(y, x, xp);
  1094.   list= where(bins(dif)<=0.0);
  1095.   if (numberof(list)) {
  1096.     /* some value (or values) of z are repeated many times --
  1097.        try to handle this by adding a small slope to the sorted y */
  1098.     dy= y(0)-y(1);
  1099.     if (!dy) dy= 1.0;
  1100.     for (eps=1.e-10 ; eps<1000.1 ; eps*=10.) {
  1101.       bins= interp(y+eps*dy*x, x, xp);
  1102.       list= where(bins(dif)<=0.0);
  1103.       if (!numberof(list)) break;
  1104.     }
  1105.     if (eps>1000.) error, "impossible error??";
  1106.   }
  1107.   return char(max(min(digitize(z,bins)-2,top),0));
  1108. }
  1109.  
  1110. /*--------------------------------------------------------------------------*/
  1111.  
  1112. extern _pl_init;
  1113. /* xxDOCUMENT _pl_init
  1114.      initializes the Gist graphics package -- DON'T EVER CALL THIS.
  1115.  */
  1116. _pl_init, GISTPATH; /* ...except right here (see paths.i) */
  1117.